Javadoc告诉你怎么维护好业务代码

共计 5345 个字符，预计需要花费 14 分钟才能阅读完成。

Javadoc写在类上面

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注作者、创建时间、参阅类等信息

概要描述

单行示例：

/**
 * Utility class used to help generate return values for calls to {@link Object#toString()}.
 */
public class ToStringUtil {

多行示例：

/**
 * Class {@code Object} is the root of the class hierarchy.
 * Every class has {@code Object} as a superclass. All objects,
 * including arrays, implement the methods of this class.
 *
 * @author  unascribed
 * @see     java.lang.Class
 * @since   JDK1.0
 */
public class Object {

@link：{@link 包名.类名#方法名(参数类型)} ：用于快速链接到相关代码

package cn.peiluming.test;

/**
 * {@link cn.peiluming.test.JavaDoc#main(String[])} 包名.类名.方法名(参数类型)
 * {@link JavaDoc#main(String[])} 省略包名
 * {@link #main(String[])} 省略类名，表示指向当前的某个方法
 * {@link cn.peiluming.test.JavaDoc} 完全限定的类名
 *
 * @author 裴路明
 * @create 2021/1/15 22:16
 */
public class JavaDoc {
    public static void main(String[] args) {

    }
}

@code：{@code text} ：将文本标记为code会被解析成<code>text</code>

• Tip：一般在Javadoc中只要涉及到类名或者方法名，都需要使用@code进行标记

详细描述

• 详细描述中可以使用html标签，如<p>、<pre>、<a>、<ul>、<i>等标签， 通常详细描述都以段落p标签开始。
• 详细描述和概要描述中间通常有一个空行来分割

package org.thymeleaf.util;

/**
 *
 * Utility methods for String objects.
 *
 * <p>
 * This class is used as a basis for the methods offered by
 * {@link org.thymeleaf.expression.Strings}, which in turn are the
 * methods offered by the {@code #strings} utility object in variable
 * expressions.
 * </p>
 *
 * @author Daniel Fern&aacute;ndez
 * @author Le Roux Bernard
 * @author Soraya S&aacute;nchez Labandeira
 * @since 1.0
 */
public final class StringUtils {

@param : 如果类中支持泛型时会通过@param来解释泛型的类型

/**
* @param <E> the type of elements in this list
*/
public interface List<E> extends Collection<E> {}

@author : 标记作者,可标记多个,也可附带邮箱地址、组织官网地址

// 纯文本作者
@author Rod Johnson

// 纯文本作者，邮件
@author Igor Hersht, igorh@ca.ibm.com

// 超链接邮件 纯文本作者
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

// 纯文本邮件
@author shane_curcuru@us.ibm.com

// 纯文本 组织
@author Apache Software Foundation

// 超链接组织地址 纯文本组织
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

@see ：标记该类相关联的类，可用在类上，也可用在方法上

/**
 * @see IntStream
 * @see LongStream
 * @see DoubleStream
 * @see <a href="package-summary.html">java.util.stream</a>
 * /
public interface Stream<T> extends BaseStream<T, Stream<T>> {}

@since ：标记文件创建时项目当时的版本号，也可是时间，表示文件创建的时间

package java.util.stream;

/**
* @since 1.8
*/
public interface Stream<T> extends BaseStream<T, Stream<T>> {}

package org.springframework.util;

/**
* @since 16 April 2001
*/
public abstract class StringUtils {}

@version ：标记当前版本

package com.sun.org.apache.xml.internal.resolver;
 /**
 * @version 1.0
 */
public class Resolver extends Catalog {}

Javadoc写在方法上

第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
第三段：文档标注，用于标注参数、返回值、异常、参阅等

@param ：后面跟参数名，再跟参数描述

@return ：跟返回值的描述

/**
     * 根据博客Id和标签Id插入中间表
     *
     * @param blogId 博客Id
     * @param tagId  标签Id
     * @return 影响行数
     */
    int insertBlogsTags(@Param("blogId") String blogId, @Param("tagId") String tagId);

@throws ：跟异常类型 异常描述, 用于描述方法内部可能抛出的异常

 /**
     * 文件复制
     *
     * @param src 源目录
     * @param destDir 目标目录
     * @param fileName 文件名
     * @throws IOException IO异常
     */
    private void copyFile(String src, String destDir, String fileName) throws IOException {

@exception : 描述方法签名throws对应的异常

/**
    *@exception SQLException if a database error occurs
    */
    protected Connection open() throws SQLException {

@see : 可以参考的类或者方法

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

@value : 标注在常量,表示常量的值

/** 默认数量 {@value} */
private static final Integer QUANTITY = 1;

@inheritDoc : 从最直接的基类中继承相关文档注释

/**
     * Returns the URI of this engine.
     * @return the URI
     */
    public abstract String engineGetURI();

/** @inheritDoc */
    public final String engineGetURI() {
        return Canonicalizer.ALGO_ID_C14N_OMIT_COMMENTS;
    }

@docRoot ：生成到文档根目录的相对路径，用于文档树页面的显示超链接

/**
     * Is this Doc item an
     * <a href="{@docRoot}/com/sun/javadoc/package-summary.html#class">ordinary
     * class</a>?
     * (i.e. not an interface, annotation type, enum, exception, or error)?
     *
     * @return true if it represents an ordinary class
     */
    boolean isOrdinaryClass();

@deprecated : 标记就特性已被新特性取代，建议不要使用，会在不久的将来删除，JDK5开始被@Deprecated注解替代

/**
     * @deprecated
     */
    @Deprecated
    public void invoke(java.rmi.server.RemoteCall call) throws Exception {

生成Javadoc

1. IDEA 的 JavaDoc 生成功能在菜单 Tools->Generate JavaDoc 项里面。

生成JavaDoc的源代码范围，不建议以整个Project
生成JavaDoc到哪个目录下面
表示的是需要生成的JavaDoc以何种语言版本展示，建议在此填写 zh_CN，这样生成的 JavaDoc 就是中文版本的
非常重要，是填写直接向 javadoc.exe 传递的参数内容

建议：-encoding UTF-8 -charset UTF-8 -windowtitle "XXwiki" -link http://docs.Oracle.com/javase/7/docs/api

• -encoding UTF-8 表示你的源代码（含有符合JavaDoc标准的注释）是基于UTF-8编码的
• -charset UTF-8 表示在处理并生成JavaDoc超文本时使用的字符集也是以UTF-8为编码
• -windowtitle 表示生成的JavaDoc超文本在浏览器中打开时，浏览器窗口标题栏显示的文字内容
• -link 涉及到很多对其他外部Java类的引用，是使用全限定名称还是带有超链接的短名称
  举例：

  我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。我创建了一个方法 public void func(String arg)，这个方法在生成 JavaDoc 时如果不指定 -link 参数，则 JavaDoc 中对该方法的表述就会自动变为 public void func(java.lang.String arg)，因为 String 这个类对我自己实现的类来讲就是外部引用的类，虽然它是 Java 标准库的类。如果指定了 -link http://docs.oracle.com/javase/7/docs/api 参数，则 javadoc.exe 在生成 JavaDoc 时，会使用 String 这样的短名称而非全限定名称 java.lang.String，同时自动为 String 短名称生成一个超链接，指向官方 JavaSE 标准文档 http://docs.oracle.com/javase/7/docs/api 中对 String 类的详细文档地址。-link 实质上是告诉 javadoc.exe 根据提供的外部引用类的 JavaDoc 地址去找一个叫 package-list 的文本文件，在这个文本文件中包含了所有外部引用类的全限定名称，因此生成的新 JavaDoc 不必使用外部引用类的全限定名，只需要使用短名称，同时可以自动创建指向其外部引用 JavaDoc 中的详细文档超链接。

JavaDoc生成完毕，如图：